ποΈGitΠ―ΡΠ°ποΈ
docs/packet_format.md 9f73fbf87002682ba3c1f3da32b7252d8ea2feda (9f73fbf8) Text, 8.83 KB
Packet Format
This document describes the MeshCore packet format.
β’ T3838380xYY indicates T383838YY in hex notation.
β’ T3838380bYY indicates T383838YY in binary notation.
β’ Bit 0 indicates the bit furthest to the right: T3838380000000X
β’ Bit 7 indicates the bit furthest to the left: T383838X0000000
Version 1 Packet Format
This is the protocol level packet structure used in MeshCore firmware v1.12.0
T282828
[header][transport_codes(optional)][path_length][path][payload]
β’ header - 1 byte
β’ 8-bit Format: T3838380bVVPPPPRR - T383838V=Version - T383838P=PayloadType - T383838R=RouteType
β’ Bits 0-1 - 2-bits - Route Type
β’ T3838380x00/T3838380b00 - T383838ROUTE_TYPE_TRANSPORT_FLOOD - Flood Routing + Transport Codes
β’ T3838380x01/T3838380b01 - T383838ROUTE_TYPE_FLOOD - Flood Routing
β’ T3838380x02/T3838380b10 - T383838ROUTE_TYPE_DIRECT - Direct Routing
β’ T3838380x03/T3838380b11 - T383838ROUTE_TYPE_TRANSPORT_DIRECT - Direct Routing + Transport Codes
β’ Bits 2-5 - 4-bits - Payload Type
β’ T3838380x00/T3838380b0000 - T383838PAYLOAD_TYPE_REQ - Request (destination/source hashes + MAC)
β’ T3838380x01/T3838380b0001 - T383838PAYLOAD_TYPE_RESPONSE - Response to T383838REQ or T383838ANON_REQ
β’ T3838380x02/T3838380b0010 - T383838PAYLOAD_TYPE_TXT_MSG - Plain text message
β’ T3838380x03/T3838380b0011 - T383838PAYLOAD_TYPE_ACK - Acknowledgment
β’ T3838380x04/T3838380b0100 - T383838PAYLOAD_TYPE_ADVERT - Node advertisement
β’ T3838380x05/T3838380b0101 - T383838PAYLOAD_TYPE_GRP_TXT - Group text message (unverified)
β’ T3838380x06/T3838380b0110 - T383838PAYLOAD_TYPE_GRP_DATA - Group datagram (unverified)
β’ T3838380x07/T3838380b0111 - T383838PAYLOAD_TYPE_ANON_REQ - Anonymous request
β’ T3838380x08/T3838380b1000 - T383838PAYLOAD_TYPE_PATH - Returned path
β’ T3838380x09/T3838380b1001 - T383838PAYLOAD_TYPE_TRACE - Trace a path, collecting SNR for each hop
β’ T3838380x0A/T3838380b1010 - T383838PAYLOAD_TYPE_MULTIPART - Packet is part of a sequence of packets
β’ T3838380x0B/T3838380b1011 - T383838PAYLOAD_TYPE_CONTROL - Control packet data (unencrypted)
β’ T3838380x0C/T3838380b1100 - reserved
β’ T3838380x0D/T3838380b1101 - reserved
β’ T3838380x0E/T3838380b1110 - reserved
β’ T3838380x0F/T3838380b1111 - T383838PAYLOAD_TYPE_RAW_CUSTOM - Custom packet (raw bytes, custom encryption)
β’ Bits 6-7 - 2-bits - Payload Version
β’ T3838380x00/T3838380b00 - v1 - 1-byte src/dest hashes, 2-byte MAC
β’ T3838380x01/T3838380b01 - v2 - Future version (e.g., 2-byte hashes, 4-byte MAC)
β’ T3838380x02/T3838380b10 - v3 - Future version
β’ T3838380x03/T3838380b11 - v4 - Future version
β’ T383838transport_codes - 4 bytes (optional)
β’ Only present for T383838ROUTE_TYPE_TRANSPORT_FLOOD and T383838ROUTE_TYPE_TRANSPORT_DIRECT
β’ T383838transport_code_1 - 2 bytes - T383838uint16_t - calculated from region scope
β’ T383838transport_code_2 - 2 bytes - T383838uint16_t - reserved
β’ T383838path_length - 1 byte - Encoded path metadata
β’ Bits 0-5 store path hash count / hop count (T3838380-63)
β’ Bits 6-7 store path hash size minus 1
β’ T3838380b00: 1-byte path hashes
β’ T3838380b01: 2-byte path hashes
β’ T3838380b10: 3-byte path hashes
β’ T3838380b11: reserved / unsupported
β’ T383838path - T383838hop_count * hash_size bytes - Path to use for Direct Routing or flood path tracking
β’ Up to a maximum of 64 bytes, defined by T383838MAX_PATH_SIZE
β’ Effective byte length is calculated from the encoded hop count and hash size, not taken directly from T383838path_length
β’ v1.12.0 firmware and older only handled legacy 1-byte path hashes and dropped packets whose path bytes exceeded 64 bytes
β’ T383838payload - variable length - Payload Data
β’ Up to a maximum 184 bytes, defined by T383838MAX_PACKET_PAYLOAD
β’ Generally this is the remainder of the raw packet data
β’ The firmware parses this data based on the provided Payload Type
β’ v1.12.0 firmware and older drops packets with T383838payload sizes larger than 184
Packet Format
βββββββββββββββββββ¬βββββββββββββββββββββββββββββββββ¬ββββββββββββββββββββββββββββββββββββββββββββββββ
β Field β Size (bytes) β Description β
βββββββββββββββββββΌβββββββββββββββββββββββββββββββββΌββββββββββββββββββββββββββββββββββββββββββββββββ€
β header β 1 β Contains routing type, payload type, and payβ¦ β
β transport_codes β 4 (optional) β 2x 16-bit transport codes (if ROUTETYPETRANSβ¦ β
β path_length β 1 β Encodes path hash size in bits 6-7 and hop cβ¦ β
β path β up to 64 (T383838MAX_PATH_SIZE) β Stores T383838hop_count * hash_size bytes of path dβ¦ β
β payload β up to 184 (T383838MAX_PACKET_PAYLOAD) β Data for the provided Payload Type β
βββββββββββββββββββ΄βββββββββββββββββββββββββββββββββ΄ββββββββββββββββββββββββββββββββββββββββββββββββ
β NOTE: see the
β Payloads
β documentation for more information about the content of specific payload types.
Header Format
Bit 0 means the lowest bit (1s place)
ββββββββ¬βββββββ¬ββββββββββββββββββ¬βββββββββββββββββββββββββββββββββββ
β Bits β Mask β Field β Description β
ββββββββΌβββββββΌββββββββββββββββββΌβββββββββββββββββββββββββββββββββββ€
β 0-1 β T3838380x03 β Route Type β Flood, Direct, etc β
β 2-5 β T3838380x3C β Payload Type β Request, Response, ACK, etc β
β 6-7 β T3838380xC0 β Payload Version β Versioning of the payload format β
ββββββββ΄βββββββ΄ββββββββββββββββββ΄βββββββββββββββββββββββββββββββββββ
Route Types
βββββββββ¬ββββββββββββββββββββββββββββββ¬βββββββββββββββββββββββββββββββββββ
β Value β Name β Description β
βββββββββΌββββββββββββββββββββββββββββββΌβββββββββββββββββββββββββββββββββββ€
β T3838380x00 β T383838ROUTE_TYPE_TRANSPORT_FLOOD β Flood Routing + Transport Codes β
β T3838380x01 β T383838ROUTE_TYPE_FLOOD β Flood Routing β
β T3838380x02 β T383838ROUTE_TYPE_DIRECT β Direct Routing β
β T3838380x03 β T383838ROUTE_TYPE_TRANSPORT_DIRECT β Direct Routing + Transport Codes β
βββββββββ΄ββββββββββββββββββββββββββββββ΄βββββββββββββββββββββββββββββββββββ
Path Length Encoding
T383838path_length is not a raw byte count. It packs both hash size and hop count:
ββββββββ¬βββββββββββββββββ¬βββββββββββββββββββββββββββββββ
β Bits β Field β Meaning β
ββββββββΌβββββββββββββββββΌβββββββββββββββββββββββββββββββ€
β 0-5 β Hop Count β Number of path hashes (T3838380-63) β
β 6-7 β Hash Size Code β Stored as T383838hash_size - 1 β
ββββββββ΄βββββββββββββββββ΄βββββββββββββββββββββββββββββββ
Hash size codes:
ββββββββββββ¬ββββββββββββ¬ββββββββββββββββββββββββββββββββ
β Bits 6-7 β Hash Size β Notes β
ββββββββββββΌββββββββββββΌββββββββββββββββββββββββββββββββ€
β T3838380b00 β 1 byte β Legacy / default mode β
β T3838380b01 β 2 bytes β Supported in current firmware β
β T3838380b10 β 3 bytes β Supported in current firmware β
β T3838380b11 β 4 bytes β Reserved / invalid β
ββββββββββββ΄ββββββββββββ΄ββββββββββββββββββββββββββββββββ
Examples:
β’ T3838380x00: zero-hop packet, no path bytes
β’ T3838380x05: 5 hops using 1-byte hashes, so path is 5 bytes
β’ T3838380x45: 5 hops using 2-byte hashes, so path is 10 bytes
β’ T3838380x8A: 10 hops using 3-byte hashes, so path is 30 bytes
Payload Types
βββββββββ¬ββββββββββββββββββββββββββ¬βββββββββββββββββββββββββββββββββββββββββββββββ
β Value β Name β Description β
βββββββββΌββββββββββββββββββββββββββΌβββββββββββββββββββββββββββββββββββββββββββββββ€
β T3838380x00 β T383838PAYLOAD_TYPE_REQ β Request (destination/source hashes + MAC) β
β T3838380x01 β T383838PAYLOAD_TYPE_RESPONSE β Response to T383838REQ or T383838ANON_REQ β
β T3838380x02 β T383838PAYLOAD_TYPE_TXT_MSG β Plain text message β
β T3838380x03 β T383838PAYLOAD_TYPE_ACK β Acknowledgment β
β T3838380x04 β T383838PAYLOAD_TYPE_ADVERT β Node advertisement β
β T3838380x05 β T383838PAYLOAD_TYPE_GRP_TXT β Group text message (unverified) β
β T3838380x06 β T383838PAYLOAD_TYPE_GRP_DATA β Group datagram (unverified) β
β T3838380x07 β T383838PAYLOAD_TYPE_ANON_REQ β Anonymous request β
β T3838380x08 β T383838PAYLOAD_TYPE_PATH β Returned path β
β T3838380x09 β T383838PAYLOAD_TYPE_TRACE β Trace a path, collecting SNR for each hop β
β T3838380x0A β T383838PAYLOAD_TYPE_MULTIPART β Packet is part of a sequence of packets β
β T3838380x0B β T383838PAYLOAD_TYPE_CONTROL β Control packet data (unencrypted) β
β T3838380x0C β reserved β reserved β
β T3838380x0D β reserved β reserved β
β T3838380x0E β reserved β reserved β
β T3838380x0F β T383838PAYLOAD_TYPE_RAW_CUSTOM β Custom packet (raw bytes, custom encryption) β
βββββββββ΄ββββββββββββββββββββββββββ΄βββββββββββββββββββββββββββββββββββββββββββββββ
Payload Versions
βββββββββ¬ββββββββββ¬βββββββββββββββββββββββββββββββββββββββββββββββββββ
β Value β Version β Description β
βββββββββΌββββββββββΌβββββββββββββββββββββββββββββββββββββββββββββββββββ€
β T3838380x00 β 1 β 1-byte src/dest hashes, 2-byte MAC β
β T3838380x01 β 2 β Future version (e.g., 2-byte hashes, 4-byte MAC) β
β T3838380x02 β 3 β Future version β
β T3838380x03 β 4 β Future version β
βββββββββ΄ββββββββββ΄βββββββββββββββββββββββββββββββββββββββββββββββββββ
Served by rngit 1.5.0 - Generated in 0.07s